Creates a control based on parameter data.

ControlRef NewControl (
    WindowRef owningWindow, 
    const Rect *boundsRect, 
    ConstStr255Param controlTitle, 
    Boolean initiallyVisible, 
    SInt16 initialValue, 
    SInt16 minimumValue, 
    SInt16 maximumValue, 
    SInt16 procID, 
    SInt32 controlReference
);

owningWindow

A pointer to the window in which you want to place the control. All coordinates pertaining to the control are interpreted in this window’s local coordinate system.

boundsRect

A pointer to a rectangle, specified in the given window’s local coordinates, that encloses the control and thus determines its size and location. When specifying this rectangle, you should follow the guidelines presented in “Dialog Box Layout”, in Mac OS 8 Human Interface Guidelines, for control placement and alignment.

controlTitle

The title string, used for push buttons, checkboxes, radio buttons, and pop-up menus. When specifying a multiple-line title, separate the lines with the ASCII character code 0x0D (carriage return). For controls that don’t use titles, pass an empty string.

initiallyVisible

A Boolean value specifying the visible/invisible state for the control. If you pass true in this parameter, NewControl draws the control immediately, without using your window’s standard updating mechanism. If you pass false, you must later use ShowControl to display the control.

initialValue

The initial setting for the control; see “Settings Values for Standard Controls”.

minimumValue

The minimum setting for the control; see “Settings Values for Standard Controls”.

maximumValue

The maximum setting for the control; see “Settings Values for Standard Controls”.

procID

The control definition ID. If the control definition function isn’t in memory, it is read in.

controlReference

The control’s reference value, which is set and used only by your application.

function result

A handle to the control described in its parameters. If NewControl runs out of memory or fails, it returns NULL.

DISCUSSION

The NewControl function creates a control structure from the information you specify in its parameters, adds the control structure to the control list for the specified window, and returns as its function result a handle to the control. You use this handle when referring to the control in most other Control Manager functions. Generally, you should use the function GetNewControl instead of NewControl, because GetNewControl is a resource-based control-creation function that allows you to localize your application without recompiling.

When an embedding hierarchy is established within a window, NewControl automatically embeds the newly created control in the root control of the owning window.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)